v8.3.0

Compare Source

Released 2025-09-15

• Improved flag option handling: Reworked the relationship between flag_value
  and default parameters for better consistency:

  • The default parameter value is now preserved as-is and passed directly
    to CLI functions (no more unexpected transformations)
  • Exception: flag options with default=True maintain backward compatibility
    by defaulting to their flag_value
  • The default parameter can now be any type (bool, None, etc.)
  • Fixes inconsistencies reported in: :issue:1992 :issue:2514 :issue:2610
    :issue:3024 :pr:3030

• Allow default to be set on Argument for nargs = -1. :issue:2164
  :pr:3030

• Show correct auto complete value for nargs option in combination with flag
  option :issue:2813

• Show correct auto complete value for nargs option in combination with flag option :issue:2813

• Fix handling of quoted and escaped parameters in Fish autocompletion. :issue:2995 :pr:3013

• Lazily import shutil. :pr:3023

• Properly forward exception information to resources registered with
  click.core.Context.with_resource(). :issue:2447 :pr:3058

• Fix regression related to EOF handling in CliRunner. :issue:2939:pr:2940

v8.2.2

Compare Source

Released 2025-07-31

• Fix reconciliation of default, flag_value and type parameters for
  flag options, as well as parsing and normalization of environment variables.
  :issue:2952 :pr:2956
• Fix typing issue in BadParameter and MissingParameter exceptions for the
  parameter param_hint that did not allow for a sequence of string where the
  underlying function _join_param_hints allows for it. :issue:2777 :pr:2990
• Use the value of Enum choices to render their default value in help
  screen. Refs :issue:2911 :pr:3004
• Fix completion for the Z shell (zsh) for completion items containing
  colons. :issue:2703 :pr:2846
• Don't include envvar in error hint when not configured. :issue:2971 :pr:2972
• Fix a rare race in click.testing.StreamMixer's finalization that manifested
  as a ValueError on close in a multi-threaded test session.
  :issue:2993 :pr:2991

v8.2.1

Compare Source

Released 2025-05-20

• Fix flag value handling for flag options with a provided type. :issue:2894
  :issue:2897 :pr:2930
• Fix shell completion for nested groups. :issue:2906 :pr:2907
• Flush sys.stderr at the end of CliRunner.invoke. :issue:2682
• Fix EOF handling for stdin input in CliRunner. :issue:2787

v8.2.0

Compare Source

Released 2025-05-10

• Drop support for Python 3.7, 3.8, and 3.9. :pr:2588 :pr:2893

• Use modern packaging metadata with pyproject.toml instead of setup.cfg.
  :pr:2438

• Use flit_core instead of setuptools as build backend. :pr:2543

• Deprecate the __version__ attribute. Use feature detection, or
  importlib.metadata.version("click"), instead. :issue:2598

• BaseCommand is deprecated. Command is the base class for all
  commands. :issue:2589

• MultiCommand is deprecated. Group is the base class for all group
  commands. :issue:2590

• The current parser and related classes and methods, are deprecated.
  :issue:2205

  • OptionParser and the parser module, which is a modified copy of
    optparse in the standard library.
  • Context.protected_args is unneeded. Context.args contains any
    remaining arguments while parsing.
  • Parameter.add_to_parser (on both Argument and Option) is
    unneeded. Parsing works directly without building a separate parser.
  • split_arg_string is moved from parser to shell_completion.

• Enable deferred evaluation of annotations with
  from __future__ import annotations. :pr:2270

• When generating a command's name from a decorated function's name, the
  suffixes _command, _cmd, _group, and _grp are removed.
  :issue:2322

• Show the types.ParamType.name for types.Choice options within
  --help message if show_choices=False is specified.
  :issue:2356

• Do not display default values in prompts when Option.show_default is
  False. :pr:2509

• Add get_help_extra method on Option to fetch the generated extra
  items used in get_help_record to render help text. :issue:2516
  :pr:2517

• Keep stdout and stderr streams independent in CliRunner. Always
  collect stderr output and never raise an exception. Add a new
  output stream to simulate what the user sees in its terminal. Removes
  the mix_stderr parameter in CliRunner. :issue:2522 :pr:2523

• Option.show_envvar now also shows environment variable in error messages.
  :issue:2695 :pr:2696

• Context.close will be called on exit. This results in all
  Context.call_on_close callbacks and context managers added via
  Context.with_resource to be closed on exit as well. :pr:2680

• Add ProgressBar(hidden: bool) to allow hiding the progressbar. :issue:2609

• A UserWarning will be shown when multiple parameters attempt to use the
  same name. :issue:2396

• When using Option.envvar with Option.flag_value, the flag_value
  will always be used instead of the value of the environment variable.
  :issue:2746 :pr:2788

• Add Choice.get_invalid_choice_message method for customizing the
  invalid choice message. :issue:2621 :pr:2622

• If help is shown because no_args_is_help is enabled (defaults to True
  for groups, False for commands), the exit code is 2 instead of 0.
  :issue:1489 :pr:1489

• Contexts created during shell completion are closed properly, fixing
  a ResourceWarning when using click.File. :issue:2644 :pr:2800
  :pr:2767

• click.edit(filename) now supports passing an iterable of filenames in
  case the editor supports editing multiple files at once. Its return type
  is now also typed: AnyStr if text is passed, otherwise None.
  :issue:2067 :pr:2068

• Specialized typing of progressbar(length=...) as ProgressBar[int].
  :pr:2630

• Improve echo_via_pager behaviour in face of errors.
  :issue:2674

  • Terminate the pager in case a generator passed to echo_via_pager
    raises an exception.
  • Ensure to always close the pipe to the pager process and wait for it
    to terminate.
  • echo_via_pager will not ignore KeyboardInterrupt anymore. This
    allows the user to search for future output of the generator when
    using less and then aborting the program using ctrl-c.

• deprecated: bool | str can now be used on options and arguments. This
  previously was only available for Command. The message can now also be
  customised by using a str instead of a bool. :issue:2263 :pr:2271

  • Command.deprecated formatting in --help changed from
    (Deprecated) help to help (DEPRECATED).
  • Parameters cannot be required nor prompted or an error is raised.
  • A warning will be printed when something deprecated is used.

• Add a catch_exceptions parameter to CliRunner. If
  catch_exceptions is not passed to CliRunner.invoke, the value
  from CliRunner is used. :issue:2817 :pr:2818

• Option.flag_value will no longer have a default value set based on
  Option.default if Option.is_flag is False. This results in
  Option.default not needing to implement __bool__. :pr:2829

• Incorrect click.edit typing has been corrected. :pr:2804

• Choice is now generic and supports any iterable value.
  This allows you to use enums and other non-str values. :pr:2796
  :issue:605

• Fix setup of help option's defaults when using a custom class on its
  decorator. Removes HelpOption. :issue:2832 :pr:2840

v8.1.8

Compare Source

Released 2024-12-19

• Fix an issue with type hints for click.open_file(). :issue:2717
• Fix issue where error message for invalid click.Path displays on
  multiple lines. :issue:2697
• Fixed issue that prevented a default value of "" from being displayed in
  the help for an option. :issue:2500
• The test runner handles stripping color consistently on Windows.
  :issue:2705
• Show correct value for flag default when using default_map.
  :issue:2632
• Fix click.echo(color=...) passing color to coloroma so it can be
  forced on Windows. :issue:2606.
• More robust bash version check, fixing problem on Windows with git-bash.
  :issue:2638
• Cache the help option generated by the help_option_names setting to
  respect its eagerness. :pr:2811
• Replace uses of os.system with subprocess.Popen. :issue:1476
• Exceptions generated during a command will use the context's color
  setting when being displayed. :issue:2193
• Error message when defining option with invalid name is more descriptive.
  :issue:2452
• Refactor code generating default --help option to deduplicate code.
  :pr:2563
• Test CLIRunner resets patched _compat.should_strip_ansi.
  :issue:2732

v8.1.7

Compare Source

Released 2023-08-17

• Fix issue with regex flags in shell completion. :issue:2581
• Bash version detection issues a warning instead of an error. :issue:2574
• Fix issue with completion script for Fish shell. :issue:2567

v8.1.6

Compare Source

Released 2023-07-18

• Fix an issue with type hints for @click.group(). :issue:2558

v8.1.5

Compare Source

Released 2023-07-13

• Fix an issue with type hints for @click.command(), @click.option(), and
  other decorators. Introduce typing tests. :issue:2558

v8.1.4

Compare Source

Released 2023-07-06

• Replace all typing.Dict occurrences to typing.MutableMapping for
  parameter hints. :issue:2255
• Improve type hinting for decorators and give all generic types parameters.
  :issue:2398
• Fix return value and type signature of shell_completion.add_completion_class
  function. :pr:2421
• Bash version detection doesn't fail on Windows. :issue:2461
• Completion works if there is a dot (.) in the program name. :issue:2166
• Improve type annotations for pyright type checker. :issue:2268
• Improve responsiveness of click.clear(). :issue:2284
• Improve command name detection when using Shiv or PEX. :issue:2332
• Avoid showing empty lines if command help text is empty. :issue:2368
• ZSH completion script works when loaded from fpath. :issue:2344.
• EOFError and KeyboardInterrupt tracebacks are not suppressed when
  standalone_mode is disabled. :issue:2380
• @group.command does not fail if the group was created with a custom
  command_class. :issue:2416
• multiple=True is allowed for flag options again and does not require
  setting default=(). :issue:2246, 2292, 2295
• Make the decorators returned by @argument() and @option() reusable when the
  cls parameter is used. :issue:2294
• Don't fail when writing filenames to streams with strict errors. Replace invalid
  bytes with the replacement character (�). :issue:2395
• Remove unnecessary attempt to detect MSYS2 environment. :issue:2355
• Remove outdated and unnecessary detection of App Engine environment. :pr:2554
• echo() does not fail when no streams are attached, such as with pythonw on
  Windows. :issue:2415
• Argument with expose_value=False do not cause completion to fail. :issue:2336